docs(examples): add metadata filter operator snippets by moroshani · Pull Request #438 · usemoss/moss

moroshani · 2026-07-18T08:29:49Z

Summary

Add four runnable TypeScript metadata filter examples for $eq, $and, $in, and $near under examples/javascript/metadata-filters/.
Share setup/query/cleanup logic so each operator snippet stays short and copyable.
Add npm scripts and README commands for the new examples.

Closes #417

Verification

npm ci
npm run type-check
npm run lint
git diff --check

Notes

The examples require real MOSS_PROJECT_ID and MOSS_PROJECT_KEY credentials to run end-to-end. I verified them with the local TypeScript and ESLint checks; at runtime they create a temporary index, run one filtered query, and delete the index.

Summary by CodeRabbit

New Features
- Added JavaScript examples for metadata filtering with equality, conjunction, inclusion, and proximity operators.
- Added sample filters for product categories, cities, and locations near Times Square.
- Added result display, timing information, cleanup, and error handling to the examples.
Documentation
- Added instructions for running each metadata filter example.
Chores
- Added npm scripts to launch the filter demonstrations.

CLAassistant · 2026-07-18T08:29:57Z

All committers have signed the CLA.

cubic-dev-ai

All reported issues were addressed across 7 files

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

moroshani · 2026-07-18T10:48:34Z

Update: I was able to complete the CLA from another device. The CLA check now shows signed. Thanks.

Copilot

Pull request overview

Adds runnable, copy-pasteable TypeScript examples demonstrating metadata filter operators in the JavaScript examples package (examples/javascript/), aligning with the repo’s goal of providing practical SDK usage snippets.

Changes:

Added four runnable operator-focused scripts for $eq, $and, $in, and $near under examples/javascript/metadata-filters/.
Introduced a shared helper to centralize setup (env, temporary index creation/loading), querying, and teardown.
Updated the JavaScript examples README and package.json scripts to make running the new samples straightforward.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
examples/javascript/README.md	Documents the new metadata filter operator samples and how to run them.
examples/javascript/package.json	Adds `npm run metadata:*` scripts to run each operator snippet.
examples/javascript/metadata-filters/shared.ts	Shared runner that creates a temporary index, performs a filtered query, prints results, and cleans up.
examples/javascript/metadata-filters/eq.ts	Runnable `$eq` filter example.
examples/javascript/metadata-filters/and.ts	Runnable `$and` composition example.
examples/javascript/metadata-filters/in.ts	Runnable `$in` filter example.
examples/javascript/metadata-filters/near.ts	Runnable `$near` geo-distance filter example.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

github-actions · 2026-07-25T02:32:50Z

Codex review

No issues found.

…r-operator-examples

coderabbitai · 2026-08-09T12:11:15Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b04a64ac-dece-4b2d-be0e-40c2b6f48782

📥 Commits

Reviewing files that changed from the base of the PR and between edd5105 and 5a0219c.

📒 Files selected for processing (1)

examples/javascript/metadata-filters/shared.ts

📝 Walkthrough

Walkthrough

Added a shared temporary-index runner and four runnable JavaScript examples for $eq, $and, $in, and $near metadata filters. Added npm scripts and README documentation for executing the examples.

Changes

Metadata filter examples

Layer / File(s)	Summary
Shared metadata filter runner `examples/javascript/metadata-filters/shared.ts`	Adds sample documents, environment validation, temporary Moss index creation and cleanup, filtered hybrid queries, and result output.
Operator samples and commands `examples/javascript/metadata-filters/*.ts`, `examples/javascript/package.json`, `examples/javascript/README.md`	Adds runnable `$eq`, `$and`, `$in`, and `$near` examples with failure handling, npm scripts, and usage documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Mergeability Score: ⚪ Minimal · up to 5a021

This PR adds localized metadata-filter examples and related documentation without any actionable merge-blocking risk remaining after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant OperatorExample
  participant runMetadataFilterExample
  participant Moss
  participant TemporaryIndex
  OperatorExample->>runMetadataFilterExample: provide metadata filter
  runMetadataFilterExample->>Moss: create temporary index
  Moss->>TemporaryIndex: load sample documents
  runMetadataFilterExample->>TemporaryIndex: execute filtered hybrid query
  TemporaryIndex-->>runMetadataFilterExample: return results
  runMetadataFilterExample->>Moss: delete temporary index

Suggested reviewers: ashvathsureshkumar

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the addition of metadata filter operator examples and matches the main pull request change.
Linked Issues check	✅ Passed	The pull request adds runnable examples for $eq, $and, $in, and $near under the examples folder, satisfying issue `#417`.
Out of Scope Changes check	✅ Passed	The code, shared setup, npm scripts, and README commands directly support the requested metadata filter examples.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/javascript/metadata-filters/shared.ts`:
- Around line 71-81: Update the temporary index name construction in the
metadata filter example to use randomUUID() as its unique suffix instead of
Date.now(). Keep the existing operator-based prefix and cleanup flow unchanged.
- Around line 102-109: Update the cleanup flow in the surrounding try/finally
logic so deleteIndex’s Promise<boolean> result must be true; when no primary
error exists, propagate cleanup failures by rejecting on a thrown error or a
non-true result. Preserve the primary operation error when both the primary
operation and cleanup fail, and keep the existing cleanupNeeded guard and
warning behavior as appropriate.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a23bedd1-9a78-45aa-a8e1-d1fc3fc0cde4

📥 Commits

Reviewing files that changed from the base of the PR and between de26a4b and edd5105.

📒 Files selected for processing (7)

examples/javascript/README.md
examples/javascript/metadata-filters/and.ts
examples/javascript/metadata-filters/eq.ts
examples/javascript/metadata-filters/in.ts
examples/javascript/metadata-filters/near.ts
examples/javascript/metadata-filters/shared.ts
examples/javascript/package.json

docs(examples): add metadata filter operator snippets

2060ba9

moroshani requested review from HarshaNalluru and r4ghu as code owners July 18, 2026 08:29

cubic-dev-ai Bot reviewed Jul 18, 2026

View reviewed changes

Comment thread examples/javascript/metadata-filters/shared.ts Outdated

Comment thread examples/javascript/metadata-filters/shared.ts Outdated

Comment thread examples/javascript/metadata-filters/shared.ts Outdated

HarshaNalluru requested a review from Copilot July 23, 2026 03:53

Copilot started reviewing on behalf of HarshaNalluru July 23, 2026 03:54 View session

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread examples/javascript/metadata-filters/shared.ts Outdated

thefounderluke mentioned this pull request Jul 24, 2026

docs: fix broken links in SDK READMEs and moss-pikachu skill #484

Closed

6 tasks

HarshaNalluru closed this Jul 25, 2026

HarshaNalluru reopened this Jul 25, 2026

moroshani added 2 commits July 29, 2026 12:27

fix(examples): make metadata filter cleanup robust

de35eea

Merge remote-tracking branch 'upstream/main' into docs/metadata-filte…

e378388

…r-operator-examples

moroshani requested a review from ashvathsureshkumar as a code owner July 29, 2026 08:59

moroshani commented Jul 29, 2026

View reviewed changes

Comment thread examples/javascript/metadata-filters/shared.ts Outdated

moroshani commented Jul 29, 2026

View reviewed changes

Comment thread examples/javascript/metadata-filters/shared.ts

Merge remote-tracking branch 'upstream/main' into docs/metadata-filte…

edd5105

…r-operator-examples

coderabbitai Bot reviewed Aug 9, 2026

View reviewed changes

Comment thread examples/javascript/metadata-filters/shared.ts Outdated

Comment thread examples/javascript/metadata-filters/shared.ts Outdated

Address metadata example cleanup review

5a0219c

Navigation Menu

Uh oh!

docs(examples): add metadata filter operator snippets - #438

docs(examples): add metadata filter operator snippets#438
moroshani wants to merge 5 commits into
usemoss:mainfrom
moroshani:docs/metadata-filter-operator-examples

moroshani commented Jul 18, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

CLAassistant commented Jul 18, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

moroshani commented Jul 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jul 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

moroshani commented Jul 18, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Notes

Summary by CodeRabbit

Uh oh!

CLAassistant commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

moroshani commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

github-actions Bot commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex review

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

moroshani commented Jul 18, 2026 •

edited by coderabbitai Bot

Loading

CLAassistant commented Jul 18, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

moroshani commented Jul 18, 2026 •

edited

Loading

github-actions Bot commented Jul 25, 2026 •

edited

Loading

coderabbitai Bot commented Aug 9, 2026 •

edited

Loading